home *** CD-ROM | disk | FTP | other *** search
/ Aminet 39 / Aminet 39 (2000)(Schatztruhe)[!][Oct 2000].iso / Aminet / mus / play / DelfMPEG.readme < prev    next >
Text File  |  2000-09-02  |  15KB  |  308 lines
  1. Short:  MPEG audio player for Delfina DSP
  2. Author: Smack/Infect! (Michael Henke)
  3. Type:   mus/play
  4.  
  5.  $VER: DelfMPEG 0.6 (Thu 27-Jul-2000)
  6.  
  7.  
  8.  #features
  9.    -plays MPEG audio files with almost no CPU load
  10.     (decoding is done completely by Delfina's DSP56002)
  11.  
  12.    -currently supports MPEG1 layer II and III
  13.  
  14.    -NEW: ARexx interface
  15.     (full 'remote control' capability)
  16.  
  17.    -multi-stage buffering system
  18.     (for smooth playback while loading from disk)
  19.  
  20.    -free software (full source code included, of course)
  21.  
  22.  
  23.  #requirements
  24.    -CPU 68020+
  25.    -AmigaOS V37+
  26.    -Delfina DSP board
  27.    -asyncio.library V39+
  28.  
  29.    -developed on: A1200 (68030+882 @ 40MHz, 16MB Fast, Delfina1200 DSP)
  30.    -tested on: various machines with Delfina1200, Delfina Lite or Plus
  31.  
  32.  
  33.  #recommended
  34.    -reqtools.library V38+
  35.    -latest version of delfina.library
  36.     (currently 4.14, see also 'known problems' section)
  37.    -some MPEG audio files :)
  38.  
  39.  
  40.  #changes since previous release
  41.    -fixed a bug in the RIFF header recognition
  42.    -implemented ARexx interface (AREXX/S option added)
  43.  
  44.  
  45.  #how to use it
  46.    DelfMPEG is a shell-only program. These options can be used:
  47.  
  48.    FILES            specify one or more filenames.
  49.                     if omitted a reqtools file requester appears.
  50.  
  51.    AREXX            activate ARexx mode.
  52.                     please read the file 'arexx.txt' for details.
  53.                     there are several example scripts provided in the 'rexx'
  54.                     sub-directory which can also be used to integrate DelfMPEG
  55.                     in tools like DOpus for instance, that's really easy now!
  56.  
  57.    VERBOSE  / -v    output more information.
  58.  
  59.    NOPLAY   / -n    don't play but just output some information.
  60.                     this works also without a Delfina board.
  61.  
  62.    SHOWTAG  / -t    display ID3v1 tag before playing.
  63.                     this is some extra information that can be appended to
  64.                     MPEG audio files. (title, artist etc.)
  65.  
  66.    MONO     / -m    decode only the left channel of stereo files.
  67.                     this option obviously degrades playback quality but it
  68.                     also saves quite a lot DSP processing time.
  69.  
  70.    DACRATE  / -d  <number>   (default: 0)
  71.                     set Delfina's codec rate to a fixed value (in kHz).
  72.                     this option allows to save some DSP power by lowering
  73.                     the DAC (Digital/Analog-Converter) rate, but playing the
  74.                     sound at a lower rate degrades quality, of course.
  75.                     the default value of 0 (zero) means "best quality", i.e.
  76.                     DAC rate will be optimal for the files to play.
  77.                     the given value is automatically rounded to the nearest
  78.                     available Delfina rate:  16, 27, 32 or 48 kHz.
  79.                     (12, 24, 36 or 48 kHz for Delfina 1200 and Plus)
  80.  
  81.    VOLUME  / -vol <number>   (default: 100)
  82.                     set the playback volume (in per cent, range 0...200).
  83.                     warning: if the volume is boosted (101...200) there might
  84.                     be distortions due to output clipping.
  85.  
  86.    FRAMEBUF / -f  <number>   (default: 100)
  87.                     set the number of read-ahead frame buffers.
  88.                     the frame buffers don't make the file reader faster but
  89.                     instead it becomes more "reliable". it works just like
  90.                     the "anti-shock" feature of portable CD players: if the
  91.                     reading process gets interrupted for a short period then
  92.                     DelfMPEG continues playing data that's already buffered.
  93.  
  94.    ASYNCBUF / -a  <number>   (default: 128)
  95.                     set the size of the AsyncIO buffer (in Kbytes).
  96.                     large IO-buffers usually improve the performance of the
  97.                     file reader but they also increase access time, which is
  98.                     the reason for the delay caused by the SHOWTAG option.
  99.  
  100.    FFSKIP   / -ff <number>   (default: 10)
  101.                     set the number of frames that are skipped during fast
  102.                     forward mode. (higher number = faster seeking)
  103.  
  104.    NOFASTL  / -nl   don't use internal DSP memory (L-data or Program memory)
  105.    NOFASTP  / -np   for the decoding routines. these options are not really
  106.                     useful except maybe for benchmark or debug purposes, they
  107.                     cause a significant slowdown of the decoder!
  108.  
  109.    NOTIMER  / -nt   don't output the position timer during playback.
  110.                     you should specify this option if you use DelfMPEG to play
  111.                     some background music while using other programs.
  112.                     (pulldown-menus, drag'n'drop etc. will block the timer
  113.                     output thus also delaying the file reader)
  114.  
  115.    STRICT   / -s    don't try to resync in case of read error.
  116.                     from version 0.4 on DelfMPEG's file reader can tolerate
  117.                     defective MPEG audio files: if it encounters invalid or
  118.                     non-audio data it continues reading in order to find the
  119.                     next valid frame header (resynchronize with the stream).
  120.                     but this behavior could cause problems in some rare cases
  121.                     (noise or even crash the decoder) so that's why it can be
  122.                     switched off with this option.
  123.  
  124.    During playback these keys can be used:
  125.  
  126.    Ctrl-F   fast forward
  127.    Ctrl-E   pause/continue
  128.    Ctrl-C   stop current file, start next file
  129.    Ctrl-D   quit program
  130.  
  131.  
  132.  #technical stuff
  133.    -MPEG audio files are made of frames. Each frame is independend from the
  134.     other frames and contains all data that's necessary to decode it (an
  135.     exception to this rule is the "bit reservoir" feature of layer III which
  136.     allows the encoder to spread data over several consecutive frames).
  137.     In MPEG1 layer II or III files every frame contains 1152 raw samples, so
  138.     the number of frames per second depends on the sampling rate (one second
  139.     of 44100 Hz sound consumes more than 38 frames). The bit rate determines
  140.     the size of the frames in bytes (or bits respectively).
  141.     In theory all frame parameters can change from one frame to the next.
  142.     DelfMPEG supports changes of these parameters inside a file:
  143.      +bit rate (some encoders can produce "variable bit rate" files)
  144.      +stereo <-> joint-stereo (Pegase uses this "dynamic joint-stereo" mode)
  145.      +error protection (it's currently ignored anyway)
  146.     For some technical reasons DelfMPEG does NOT support files which contain
  147.     changes of these parameters:
  148.      -MPEG layer
  149.      -number of channels (mono <-> stereo)
  150.      -sampling rate
  151.     But I think this is not a big restriction in everyday life.
  152.     Note: the file information that is displayed before playing is taken from
  153.     the first frame only and the duration is just a "guess" based on it.
  154.  
  155.  
  156.    -here are a few benchmark results, taken on my A1200 using the "beta 46"
  157.     version of delfina.library 4.15  (DSP load measured with DelfLoad)
  158.     "Delfina 1200: delfina.library v4.15, 31 K memory, 73.7 MHz DSP"
  159.  
  160.     DSP load in idle state: 13%
  161.     DSP load during playback - layer II  128kbps 44100Hz j-stereo
  162.      normal (no options):               45%  (full quality)
  163.      with NOFASTL and NOFASTP options:  66%  (full quality)
  164.      with MONO option:                  35%  (degraded quality)
  165.      with DACRATE=24 option:            38%  (degraded quality)
  166.     DSP load during playback - layer III 128kbps 44100Hz j-stereo
  167.      normal (no options):               52%  (full quality)
  168.      with NOFASTL and NOFASTP options:  76%  (full quality)
  169.      with MONO option:                  38%  (degraded quality)
  170.      with DACRATE=24 option:            44%  (degraded quality)
  171.  
  172.     conclusions:
  173.      -the 74 MHz DSP of the new Delfina models (1200 and Plus) offers more
  174.       than enough power for realtime decoding in all these situations.
  175.       (even 40 MHz are sufficient for mp3 playback - hello Lite users!)
  176.      -notice the big difference between the "normal" and "NOFAST" results!
  177.       the use of some internal DSP memory in the critical subroutines gives
  178.       a significant speedup. (an important area for DSP code optimizations)
  179.      -the MONO option does not exactly halve the effective DSP load. this is
  180.       because not all decoding steps can be skipped for the omitted channel,
  181.       real single-channel files require less processing.
  182.  
  183.  
  184.    -in VERBOSE mode DelfMPEG could print a few warnings:
  185.      -NO_INPUT_DATA means that the file reader could not supply the decoder
  186.       with new data in time (results in "stretched" sound, you can test this
  187.       by blocking the position timer output - and also the file reader)
  188.      -DECODER_BUSY means that the DSP decoding routine did not finish in time
  189.       before the next call (results in "jerky" or "stuttering" sound, can be
  190.       tested by using the mp3 decoder on a slow DSP;)
  191.      -MP3_MAINDATA_ERROR means that the layer III file contained corrupted
  192.       data (if you encounter this warning please check the mp3 file using
  193.       another player (such as MPEGA), if the file is really damaged then all
  194.       decoders should complain about it)
  195.  
  196.  
  197.  #known problems
  198.    -DelfMPEG only recognizes MPEG1 audio files.
  199.     not supported: MPEG2 or mixed audio/video files.
  200.  
  201.    -some mp3 files are not played correctly! what's wrong with DelfMPEG?
  202.     1) DSP load approaches or exceeds the 100% limit on slow Delfinas.
  203.        symptom: audible "drop-outs", DECODER_BUSY warning in VERBOSE mode.
  204.        actions: use MONO or DACRATE options to reduce DSP load (and quality)
  205.                 or overclock your Delfina Lite (some guys have done this and
  206.                 they live a happier life now;) or purchase a Delfina Plus.
  207.     2) intensity stereo decoding is not implemented yet.
  208.        symptom: audible distortions, INTENSITY_STEREO warning in VERBOSE mode.
  209.        actions: send me gifts, money or at least some nice emails and give me
  210.                 the motivation to implement this. :-)
  211.                 please consider: in my large collection of mp3's there are
  212.                 only two files that are encoded with this scheme.  high
  213.                 quality encoders (use LAME, it's the best!) don't use the
  214.                 intensity stereo scheme at all!
  215.     3) in VERBOSE mode an "unexpected EOF" error is reported for some files.
  216.        symptom: just the error message.
  217.        actions: this is a minor glitch in the file reader, it shouldn't have
  218.                 any audible effects. that's why I decided to ignore it, you
  219.                 can try and convince me to fix it. :-)
  220.  
  221.    -DelfMPEG causes deadlocks/crashes.
  222.     1) delfina.library 4.14  -  the "fake crash" bug
  223.        symptom: soon after DelfMPEG started playing the "Delfina crashed"
  224.                 requester appears; DelfLoad display jumps to 100%.
  225.        actions: wait for Petsoff to release a fixed delfina.library.
  226.                 ignore the "Delfina crashed" requester (that's right, do not
  227.                 reply it while DelfMPEG is playing).
  228.                 or you could use an older version of delfina.library (4.13 or
  229.                 lower) - not recommended, there seem to be other problems.
  230.     2) delfina.library 4.14 and lower  -  the "AHI killer" bug
  231.        symptom: AHI and DelfAIFF crash if used after DelfMPEG. the system
  232.                 freezes and must be rebooted.
  233.        actions: wait for Petsoff to release a fixed delfina.library.
  234.                 use the NOFASTP option of DelfMPEG, it avoids the bug but it
  235.                 also slows down the decoder!
  236.                 or use the workaround: quit DelfMPEG and all other Delfina
  237.                 programs, use "avail flush" to remove delfina.library from
  238.                 memory and then start your AHI programs.
  239.  
  240.  
  241.  #acknowledgements
  242.    DelfMPEG uses ideas/code from:
  243.    -MPEG Audio Layer II decoder by Fredrik Noring and Tomas Berndtsson
  244.     (an mp2 player for Atari Falcon, DSP56K code)
  245.    -amp11 by Niklas Beisert (clean and fast C++ code)
  246.    -FalcAMP by Denis "STGhost" Huguet and David "Splash" Carrere
  247.     (an mp3 player for Atari Falcon, DSP56K code)
  248.    -reference code by MPEG Software Simulation Group ("the original" C code)
  249.  
  250.  
  251.  #author
  252.    mailto: smack@smack.de
  253.  
  254.    DelfMPEG - MPEG audio player for Delfina DSP
  255.    Copyright (C) 1999, 2000  Michael Henke
  256.  
  257.    This program is free software; you can redistribute it and/or modify
  258.    it under the terms of the GNU General Public License as published by
  259.    the Free Software Foundation; either version 2 of the License, or
  260.    (at your option) any later version.
  261.  
  262.    This program is distributed in the hope that it will be useful,
  263.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  264.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  265.    GNU General Public License for more details.
  266.  
  267.    You should have received a copy of the GNU General Public License
  268.    along with this program; if not, write to the Free Software
  269.    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  270.  
  271.  
  272. ============================= Archive contents =============================
  273.  
  274. Original  Packed Ratio    Date     Time    Name
  275. -------- ------- ----- --------- --------  -------------
  276.     2991    1376 53.9% 27-Jul-00 19:02:44 +arexx.txt
  277.    18113    7000 61.3% 27-Jul-00 19:02:44 +COPYING
  278.   109464   61527 43.7% 27-Jul-00 19:02:44 +DelfMPEG
  279.    13056    5293 59.4% 27-Jul-00 19:02:44 +DelfMPEG.readme
  280.      734     365 50.2% 27-Jul-00 19:02:44 +.readme
  281.       94      91  3.1% 27-Jul-00 19:02:44 +cont
  282.      444     276 37.8% 27-Jul-00 19:02:44 +forward
  283.      481     288 40.1% 27-Jul-00 19:02:44 +goto
  284.     1210     544 55.0% 27-Jul-00 19:02:44 +info
  285.      407     232 42.9% 27-Jul-00 19:02:44 +launch
  286.       92      87  5.4% 27-Jul-00 19:02:44 +pause
  287.      579     325 43.8% 27-Jul-00 19:02:44 +play
  288.      582     326 43.9% 27-Jul-00 19:02:44 +pplay
  289.       90      87  3.3% 27-Jul-00 19:02:44 +quit
  290.      421     268 36.3% 27-Jul-00 19:02:44 +rewind
  291.       90      87  3.3% 27-Jul-00 19:02:44 +stop
  292.      328     208 36.5% 27-Jul-00 19:02:44 +vol
  293.     8754    2081 76.2% 27-Jul-00 19:02:44 +arexx.c
  294.     3289    1490 54.6% 27-Jul-00 19:02:44 +CHANGES
  295.    40971   11580 71.7% 27-Jul-00 19:02:44 +DelfMPEG.c
  296.    63138   12632 79.9% 27-Jul-00 19:02:44 +MP2.a56
  297.     1418     682 51.9% 27-Jul-00 19:02:44 +MP2.h
  298.    80544   21619 73.1% 27-Jul-00 19:02:44 +MP3.a56
  299.     1549     728 53.0% 27-Jul-00 19:02:44 +MP3.h
  300.    82305   29467 64.1% 27-Jul-00 19:02:44 +MP3_pow43tab.h
  301.     5178    1093 78.8% 27-Jul-00 19:02:44 +MP3_quantab.h
  302.     3305    1497 54.7% 27-Jul-00 19:02:44 +PCM.a56
  303.     1363     654 52.0% 27-Jul-00 19:02:44 +PCM.h
  304.      126      93 26.1% 27-Jul-00 19:02:44 +SCOPTIONS
  305.      358     150 58.1% 27-Jul-00 19:02:44 +smakefile
  306. -------- ------- ----- --------- --------
  307.   441474  162146 63.2% 28-Jul-100 04:54:44   30 files
  308.